JIIT Placement Alerts

Documentation

Back to Home
Live GitHub
Getting Started

Architecture & Design

API Architecture & Endpoints
Error Handling & Rate Limiting REST API Endpoints Server Architecture Telegram Bot API
Data Flow & Processing Pipeline
Email Processing Orchestration Notification Flow Distribution Update Flow Processing
Database Schema & Data Model
Collection Schemas & Field Definitions Data Flow & Collection Relationships Indexing Strategy & Performance Optimization Query Patterns & Practical Examples
Service Architecture
Administrative Services Content Processing Services Core Services Formatting Services
Deployment Architecture Design Principles

Core Services

Email Processing Services
Email Notice Service Notice Formatter Service Placement Notification Formatter Placement Service
Database Service Notification Service Telegram Service Web Push Service

Data Processing & Content Extraction

Content Formatting & Enhancement Email Processing & Classification LLM Powered Content Extraction Statistics Calculation & Analytics

Server Components

Scheduler Server Telegram Bot Server Webhook Server
API Reference
Configuration & Environment
Database Schema & Models
Deployment & Operations
Development & Contributing
Troubleshooting & FAQ
Home Projects JIIT Placement Alerts Core Services Email Processing Services Placement Notification Formatter

Placement Notification Formatter

Referenced Files
placement_notification_formatter.pyplacement_service.pynotification_service.pytelegram_client.pydatabase_service.pymain.pyplacement_offers.json
#

Table of Contents#

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

#

Introduction#

The Placement Notification Formatter is a specialized service responsible for transforming structured placement offer data into notification-ready content for delivery channels. This system handles the complete lifecycle from raw placement offer extraction to formatted message delivery, with particular emphasis on creating readable, informative notifications for Telegram and other channels.

The formatter operates independently of database operations, maintaining clean separation of concerns while integrating seamlessly with the broader notification ecosystem. It processes placement events (new offers and updates) and generates standardized, human-friendly content that preserves important details while optimizing for readability and character limits.

#

Project Structure#

The placement notification system is organized within the application’s services layer, with clear boundaries between data extraction, formatting, and delivery components.

graph TB subgraph "Data Sources" A[Email Processing] B[Structured Data Files] C[Database Records] end subgraph "Processing Layer" D[Placement Service] E[Placement Notification Formatter] F[Notice Formatter Service] end subgraph "Delivery Layer" G[Notification Service] H[Telegram Client] I[Database Service] end A --> D B --> D C --> E D --> E E --> F F --> G G --> H G --> I

Diagram sources

Section sources

#

Core Components#

The Placement Notification Formatter consists of several key components that work together to transform raw placement data into notification-ready content:

Data Models and Structures#

The formatter defines comprehensive data models for representing placement offers, students, roles, and notification documents. These models ensure type safety and provide clear contracts for data transformation.

Formatting Algorithms#

Specialized algorithms handle the transformation of raw placement data into human-readable notifications, with particular attention to:

  • Company information presentation

  • Student listing organization

  • Package details formatting

  • Selection criteria summarization

Template Generation#

The system implements template-based approaches for different placement scenarios, ensuring consistent formatting across various types of placement events.

Section sources

#

Architecture Overview#

The placement notification system follows a layered architecture with clear separation of concerns and dependency injection for testability.

sequenceDiagram participant Email as "Email Source" participant Service as "Placement Service" participant Formatter as "Placement Notification Formatter" participant DB as "Database Service" participant Notifier as "Notification Service" participant Telegram as "Telegram Client" Email->>Service : Raw Placement Email Service->>Service : Extract & Validate Data Service->>DB : Save Placement Offer Service->>Formatter : Generate Events Formatter->>Formatter : Format Notification Formatter->>DB : Save Notice Document Notifier->>DB : Fetch Unsent Notices Notifier->>Telegram : Send Formatted Message Telegram-->>Notifier : Delivery Confirmation Notifier->>DB : Mark as Sent

Diagram sources

#

Detailed Component Analysis#

PlacementNotificationFormatter Class#

The core formatter class implements sophisticated algorithms for transforming placement offer data into notification-ready content.

Data Model Definitions#

The formatter defines several Pydantic models that serve as the foundation for data transformation:

classDiagram class RoleData { +string role +float package +string package_details } class StudentData { +string name +string enrollment_number +string email +string role +float package } class OfferData { +string company +RoleData[] roles +StudentData[] students_selected +int number_of_offers +string time_sent } class NewOfferEvent { +string type +string company +string offer_id +OfferData offer_data +RoleData[] roles +int total_students +string time_sent +string email_sender } class UpdateOfferEvent { +string type +string company +string offer_id +StudentData[] newly_added_students +RoleData[] roles +int total_students +string email_sender +string time_sent } class NoticeDocument { +string id +string title +string content +string author +string type +string source +string placement_offer_ref +string formatted_message +int createdAt +int updatedAt +bool sent_to_telegram +bool is_update +int new_students_count } NewOfferEvent --> OfferData : "contains" UpdateOfferEvent --> StudentData : "contains" NoticeDocument --> OfferData : "references"

Diagram sources

Package Formatting Algorithm#

The formatter includes a sophisticated package formatting algorithm that converts raw numeric values into human-readable strings:

flowchart TD Start([Package Input]) --> CheckNull{"Is Package Null?"} CheckNull --> |Yes| ReturnNull["Return None"] CheckNull --> |No| ConvertType["Convert to Float"] ConvertType --> CheckValue{"Value >= 100000?"} CheckValue --> |Yes| FormatLPA["Format as X.X LPA"] CheckValue --> |No| FormatRupees["Format as Rupees"] FormatLPA --> End([Formatted String]) FormatRupees --> End ReturnNull --> End

Diagram sources

Role Breakdown Algorithm#

The role breakdown algorithm organizes student placements by role with intelligent counting and formatting:

flowchart TD Start([Student List]) --> BuildMap["Build Role -> Package Mapping"] BuildMap --> InitCounts["Initialize Role Counts"] InitCounts --> IterateStudents["Iterate Through Students"] IterateStudents --> CheckRole{"Student Has Role?"} CheckRole --> |Yes| CountRole["Increment Role Count"] CheckRole --> |No| CheckDefault{"Has Default Role?"} CheckDefault --> |Yes| CountDefault["Increment Default Role"] CheckDefault --> |No| CountUnspecified["Increment Unspecified Count"] CountRole --> NextStudent["Next Student"] CountDefault --> NextStudent CountUnspecified --> NextStudent NextStudent --> MoreStudents{"More Students?"} MoreStudents --> |Yes| IterateStudents MoreStudents --> |No| BuildLines["Build Display Lines"] BuildLines --> FormatLines["Format with Package Info"] FormatLines --> End([Breakdown Text])

Diagram sources

Notification Template Generation#

The formatter implements template-based approaches for different placement scenarios:

Final Selection Templates:

  • Company placement summary with student count

  • Role breakdown with package information

  • Time sent information when available

  • Congratulations message

Update Templates:

  • Incremental placement update with new student count

  • Total placement counter

  • New position breakdown

  • Update-specific messaging

Section sources

Integration with Notification System#

The formatter integrates deeply with the broader notification ecosystem through several key mechanisms:

Database Integration#

The formatter maintains loose coupling with database operations through dependency injection, allowing for flexible storage backends while preserving clean separation of concerns.

Channel Delivery#

Notifications are delivered through a unified notification service that supports multiple channels including Telegram and web push notifications.

Event Processing Pipeline#

The formatter participates in a complete pipeline that includes email processing, data extraction, validation, and notification delivery.

Section sources

#

Dependency Analysis#

The placement notification system exhibits well-structured dependencies that promote maintainability and testability.

graph TB subgraph "External Dependencies" A[Pydantic] B[LangChain] C[BeautifulSoup] D[Requests] end subgraph "Internal Dependencies" E[Database Service] F[Telegram Client] G[Notification Service] H[Placement Service] end subgraph "Formatter Components" I[PlacementNotificationFormatter] J[NoticeFormatterService] K[OfficialPlacementService] end A --> I B --> H C --> H D --> K E --> I E --> J F --> G G --> I H --> I I --> J

Diagram sources

Coupling and Cohesion Analysis#

The system demonstrates excellent separation of concerns with low internal coupling and high external coupling. The formatter focuses solely on presentation logic while delegating data persistence and delivery to specialized services.

Circular Dependencies#

No circular dependencies were identified in the placement notification system, contributing to its maintainability and testability.

Section sources

#

Performance Considerations#

The placement notification formatter is designed with several performance optimizations:

Memory Efficiency#

  • Streaming processing of large datasets

  • Lazy evaluation of formatted content

  • Efficient string concatenation using join operations

Processing Optimizations#

  • Early termination for non-relevant emails

  • Caching of frequently accessed data

  • Minimal object creation during formatting

Scalability Features#

  • Asynchronous processing capabilities

  • Configurable batch sizes

  • Resource-aware operation limits

#

Troubleshooting Guide#

Common issues and their solutions when working with the placement notification formatter:

Data Transformation Issues#

  • Problem: Incorrect package formatting

    • Solution: Verify numeric values are properly converted and handle edge cases

    • Check: Ensure package values are numeric and within expected ranges

  • Problem: Missing role information in student listings

    • Solution: Implement default role assignment when single role exists

    • Check: Validate role assignment logic for multi-role scenarios

Notification Delivery Problems#

  • Problem: Telegram message delivery failures

    • Solution: Check rate limiting and implement exponential backoff

    • Check: Verify bot token and chat ID configuration

  • Problem: Database storage conflicts

    • Solution: Implement conflict resolution and retry logic

    • Check: Verify unique identifier generation and collision handling

Integration Challenges#

  • Problem: Email processing inconsistencies

    • Solution: Implement robust error handling and retry mechanisms

    • Check: Validate email parsing and extraction logic

Section sources

#

Conclusion#

The Placement Notification Formatter represents a sophisticated solution for transforming structured placement offer data into notification-ready content. Its design emphasizes clean separation of concerns, extensibility, and maintainability while providing robust functionality for handling various placement scenarios.

The system’s modular architecture enables easy integration with different data sources and delivery channels, while its comprehensive error handling and performance optimizations ensure reliable operation in production environments. The formatter’s ability to adapt to different placement types and maintain consistent presentation standards makes it an essential component of the broader notification ecosystem.

Through careful attention to data modeling, formatting algorithms, and integration patterns, the Placement Notification Formatter provides a solid foundation for scalable placement notification systems that can evolve with changing requirements and data sources.

Previous Notice Formatter Service
Next Placement Service